3D Graphics Programming with QuickDraw 3D 1.5.4
Previous | QD3D Book | Overview | Chapter Contents | Next |
Managing Unknown Objects
QuickDraw 3D creates an unknown object when it encounters an unrecognized type of object while reading a metafile. Your application might know how to handle objects of that type, so QuickDraw 3D provides routines that you can use to get the type and contents of an unknown object.
You cannot explicitly create an unknown object.
Q3Unknown_GetType
You can use the Q3Unknown_GetType function to get the type of an unknown object.
TQ3ObjectType Q3Unknown_GetType (TQ3UnknownObject unknownObject);
DESCRIPTION
The Q3Unknown_GetType function returns, as its function result, the type of the unknown object specified by the unknownObject parameter. If successful, Q3Unknown_GetType returns one of these constants:
kQ3UnknownTypeBinary
kQ3UnknownTypeText
If the type cannot be determined or is invalid, Q3Unknown_GetType returns the value kQ3ObjectTypeInvalid .
Q3Unknown_GetDirtyState
You can use the Q3Unknown_GetDirtyState function to get the current dirty state of an unknown object.
TQ3Status Q3Unknown_GetDirtyState (
TQ3UnknownObject unknownObject,
TQ3Boolean *isDirty);
- unknownObject
- An unknown object.
- isDirty
- On exit, a Boolean value that indicates whether the specified unknown object is dirty ( kQ3True ) or not ( kQ3False ).
DESCRIPTION
The Q3Unknown_GetDirtyState function returns, in the isDirty parameter, the current dirty state of the unknown object specified by the unknownObject parameter. The dirty state of an unknown object is a Boolean value that indicates whether an unknown object is preserved in its original state ( kQ3False ) or should be updated when written back to the file object from which it was originally read ( kQ3True ).
An unknown object is marked as dirty when it's first read into memory. You can mark the object as not dirty (by calling Q3Unknown_SetDirtyState ) if you know that no state or contextual information has changed in the object. The application that generated the unknown data is responsible for either discarding any dirty data or attempting to preserve it.
Q3Unknown_SetDirtyState
You can use the Q3Unknown_SetDirtyState function to set the dirty state of an unknown object.
TQ3Status Q3Unknown_SetDirtyState (
TQ3UnknownObject unknownObject,
TQ3Boolean isDirty);
Q3UnknownText_GetData
You can use the Q3UnknownText_GetData function to get the data of an unknown text object.
TQ3Status Q3UnknownText_GetData (
TQ3UnknownObject unknownObject,
TQ3UnknownTextData *unknownTextData);
DESCRIPTION
The Q3UnknownText_GetData function returns, in the objectName and contents fields of the unknown text data structure pointed to by the unknownTextData parameter, pointers to the name and contents of an unknown text object (that is, an unknown object of type kQ3UnknownTypeText ) specified by the unknownObject parameter. The contents field of the unknown text data structure points to the data stored in the text metafile, excluding any excess white space and any delimiter characters (that is, outermost parentheses).
Your application is responsible for allocating the memory occupied by the unknownTextData parameter. Q3UnknownText_GetData allocates memory to hold the name and contents pointed to by the fields of that structure. You must make certain to call Q3UnknownText_EmptyData to release the memory allocated by Q3UnknownText_GetData when you are finished using the data.
Q3UnknownText_EmptyData
You can use the Q3UnknownText_EmptyData function to dispose of the memory allocated by a previous call to Q3UnknownText_GetData .
TQ3Status Q3UnknownText_EmptyData (
TQ3UnknownTextData *unknownTextData);
Q3UnknownBinary_GetData
You can use the Q3UnknownBinary_GetData function to get the data of an unknown binary object.
TQ3Status Q3UnknownBinary_GetData (
TQ3UnknownObject unknownObject,
TQ3UnknownBinaryData *unknownBinaryData);
- unknownObject
- An unknown binary object.
- unknownBinaryData
- A pointer to an unknown binary data structure.
DESCRIPTION
The Q3UnknownBinary_GetData function returns, in the contents field of the unknown binary data structure pointed to by the unknownBinaryData parameter, a pointer to a copy of the contents of the unknown binary object (that is, an unknown object of type kQ3UnknownTypeBinary ) specified by the unknownObject parameter. Q3UnknownBinary_GetData also returns, in the objectType and size fields of the unknown binary data structure, the type of the unknown binary object and the size, in bytes, of the data pointed to by the contents field.
Your application is responsible for allocating the memory occupied by the unknownBinaryData parameter. Q3UnknownBinary_GetData allocates memory to hold the data pointed to by the contents field of that structure. You must make certain to call Q3UnknownBinary_EmptyData to release the memory allocated by Q3UnknownBinary_GetData when you are finished using the data.
Q3UnknownBinary_EmptyData
You can use the Q3UnknownBinary_EmptyData function to dispose of the memory allocated by a previous call to Q3UnknownBinary_GetData .
TQ3Status Q3UnknownBinary_EmptyData (
TQ3UnknownBinaryData *unknownBinaryData);
Q3UnknownBinary_GetTypeString
You can use the Q3UnknownBinary_GetTypeString function to get the type string of an unknown binary object.
TQ3Status Q3UnknownBinary_GetTypeString (
TQ3UnknownObject unknownObject,
char **typeString);
- unknownObject
- An unknown binary object.
- typeString
- A handle to the type string of an unknown binary data structure.
DESCRIPTION
The Q3UnknownBinary_GetTypeString function returns a handle to the type string of an unknown binary object.
Your application is responsible for allocating the memory occupied by the typeString parameter. You must call Q3UnknownBinary_EmptyTypeString to release the memory allocated by Q3UnknownBinary_GetTypeString when you are finished using the data.
Q3UnknownBinary_EmptyTypeString
You can use the Q3UnknownBinary_EmptyTypeString function to dispose of the memory allocated by a previous call to Q3UnknownBinary_GetTypeString .
TQ3Status Q3UnknownBinary_EmptyTypeString (
char **typeString);
© 1997 Apple Computer, Inc.
Previous | QD3D Book | Overview | Chapter Contents | Next |